---
title: 貢獻指南
description: 貢獻指南
---

# 為 FastExcel 做貢獻

FastExcel 歡迎社群中的每一位使用者和開發者成為貢獻者。無論是回報問題、改進文件、提交程式碼，還是提供技術支援，您的參與將有助於使 FastExcel 變得更好。

---

## 回報問題

我們鼓勵使用者在使用 FastExcel 的過程中隨時提供回饋。您可以透過 [NEW ISSUE](https://github.com/CodePhiliaX/fastexcel/issues/new/choose) 提交問題。

### 高品質問題回報

為了提高溝通效率，請在提交問題前：  
1. **搜尋現有問題**：檢查您的問題是否已被回報。如果已存在，請直接在現有問題下評論補充詳細資訊，而不是創建新問題。  
2. **使用問題模板**：問題模板位於 [ISSUE TEMPLATE](./.github/ISSUE_TEMPLATE)，請按照模板要求填寫，以確保問題描述準確且完整。

以下情況適合提交新問題：
- Bug 回報
- 新功能需求
- 效能問題
- 功能提案或設計
- 文件改進
- 測試覆蓋率優化
- 需要技術支援
- 其他與專案相關的問題

> **注意**：請勿在問題中包含敏感資訊，如密碼、金鑰、伺服器位址或私人資料。

---

## 貢獻程式碼與文件

所有對 FastExcel 的改進均可透過 Pull Request (PR) 實現。無論是修復 Bug、優化程式碼、增強功能，還是改進文件，都非常歡迎！

### 您可以貢獻的方向
- 修復錯別字
- 修復 Bug
- 刪除冗余程式碼
- 添加測試案例
- 增強功能
- 添加註釋以提升程式碼可讀性
- 優化程式碼結構
- 改進或完善文件

**原則**：**任何有助於專案改進的 PR 都值得鼓勵！**

在提交 PR 前，請熟悉以下指南：
1. [工作區準備](#工作區準備)
2. [分支定義](#分支定義)
3. [提交規則](#提交規則)
4. [PR 說明](#pr說明)

---

### 工作區準備

確保您已註冊 GitHub 帳號，並按照以下步驟完成本地開發環境配置：
1. **Fork 倉庫**：在 FastExcel 的 [GitHub 頁面](https://github.com/CodePhiliaX/fastexcel) 點擊 `Fork` 按鈕，將專案複製到您的 GitHub 帳戶下，例如：`https://github.com/<your-username>/fastexcel`。
2. **克隆程式庫**：執行以下命令將 Fork 的專案克隆到本地：
   ```bash
   git clone git@github.com:<your-username>/fastexcel.git
   ```
3. **設定上游倉庫**：將官方倉庫設定為 `upstream`，方便同步更新：
   ```bash
   git remote add upstream git@github.com:CodePhiliaX/fastexcel.git
   git remote set-url --push upstream no-pushing
   ```
   執行 `git remote -v` 可檢查配置是否正確。

---

### 分支定義

在 FastExcel 中，所有貢獻應基於 `main` 開發分支。此外，還有以下分支類型：
- **release 分支**：用於版本發布（如 `0.6.0`, `0.6.1`）。
- **feature 分支**：用於開發較大的功能。
- **hotfix 分支**：用於修復重要 Bug。

提交 PR 時，請確保變更基於 `main` 分支。

---

### 提交規則

#### 提交訊息
請確保提交訊息清晰且具有描述性，遵循以下格式：
- **docs**: 更新文件，例如 `docs: 更新 PR 提交指南`。
- **feature**: 新功能，例如 `feature: 支援並行寫入`。
- **bugfix**: 修復 Bug，例如 `bugfix: 修復空指標異常`。
- **refactor**: 重構程式碼，例如 `refactor: 優化資料處理邏輯`。
- **test**: 增加或改進測試，例如 `test: 添加單元測試`。

不建議使用模糊的提交訊息，如：  
- ~~修復問題~~  
- ~~更新程式碼~~  

如果需要幫助，請參考 [如何撰寫 Git 提交訊息](http://chris.beams.io/posts/git-commit/)。

#### 提交內容
一次提交應包含完整且可審查的更改，確保：
- 避免提交過於龐大的改動。
- 每次提交內容獨立且可通過 CI 測試。

另外，請確保提交時配置正確的 Git 使用者資訊：
```bash
git config --get user.name
git config --get user.email
```

---

### PR 說明

為了幫助審閱者快速了解 PR 的內容和目的，請使用 [PR 模板](./.github/PULL_REQUEST_TEMPLATE.md)。詳細的描述將極大提高程式碼審閱效率。

---

## 測試案例貢獻

任何測試案例的貢獻都值得鼓勵，尤其是單元測試。建議在對應模組的 `test` 目錄中創建 `XXXTest.java` 檔案，推薦使用 JUnit5 框架。

---

## 其他參與方式

除了直接貢獻程式碼，以下方式同樣是對 FastExcel 的寶貴支持：
- 回答其他使用者的問題。
- 幫助審閱他人的 PR。
- 提出改進建議。
- 撰寫技術部落格，宣傳 FastExcel。
- 在社群中分享專案相關知識。

---

## 程式碼風格

請遵循 [阿里巴巴 Java 編碼規範](https://alibaba.github.io/Alibaba-Java-Coding-Guidelines/) 進行程式碼撰寫。  
您可以選擇安裝以下插件（非必需）以幫助檢查程式碼風格：
- **IntelliJ IDEA 插件**：[安裝指南](https://github.com/alibaba/p3c/blob/master/idea-plugin/README.md)
- **Eclipse 插件**：[安裝指南](https://github.com/alibaba/p3c/blob/master/eclipse-plugin/README.md)

---

**最後，感謝您對 FastExcel 的支持！每一份幫助，都是我們前進的動力。**